feat(engine-mcp): a capability search finds a symbol by name and answers in one call (PRD-865) - #644

PRD: docs/PRDs/done/PRD-865-capability-search-finds-by-name-and-answers-in-one-call.md (100%: 3/3 phases, 4/4 acceptance criteria)

One commit on origin/develop (e897bf827). Rebased after #633–#645 landed: the previous head carried nine pre-squash doc commits that are now on develop, which is what made the PR conflicting.

Also lands the develop red this PR was queued behind (AGENTS.md: fix a red on develop in the PR already in flight). develop's board has been red since #639/#640, which is why every merge group — including this PR's three attempts — ejected: golden-path-template (platformer) failed with TN_PLAYTEST_BRIDGE_MISSING because the platformer kit still booted /src/main.ts on the page thread while the golden path serves index.html and asserts threads on. The kit now has the worker entry pair the starter shipped in #574: index.html → src/worker-page.ts, src/worker.ts, main.html for the page-thread arm, and the two-entry build. Its game code is worker-safe (render/loading.ts guards its canvas behind typeof document). That is the only reason this PR is not strictly PRD-865's scope.

What changed

engine_search_capabilities now finds a capability by its exported symbol name and answers in one call.

• A name is indexed. The tokenizer splits camelCase; a request that spells a name as a run of whole words leads with that symbol, case- and separator-insensitive (mergeparts, characterbody3d), including a node named inside a sentence (GPUParticles3D sparks, Area3D trigger). The lead scales with how much of the request the name accounts for and a longer name wins a tie, so GPUParticles3D beats the generic Particles while first person view with a weapon held in the hand still answers the camera, not the View symbol.
• Names carry their own index (digits stripped: GPUParticles3D reads as gpu particles) and the summary is scored over it at low weight — that is what makes a thinly described entry (traa) findable. It stays apart from the prose index on purpose: folding it in cost SnowField its row in the recall budget.
• A row answers. ICapabilitySearchResult gains signature, overrides and deprecated: a row is the detail minus situations/aliases. AGENTS.md, agent-docs/kit-router.md, the shared threenative-capabilities skill and all sixteen kit AGENTS.md/CLAUDE.md now say read every row and call engine_capability_detail only for a symbol the search did not return.
• MCP text is compact JSON. Indentation cost 11.8% of every response; threenative engine_* … from a shell re-indents its own copy.
• A frozen gold set and a two-arm A/B: 150 real queries from 26 .threenative/engine-mcp.log files, 100 dev / 50 heldout, 20 exact-symbol, held-out sha256 frozen in the fixture and in the PRD. Labels were written by a fresh opus process that read only the logs and the manifest; 58 rows it judged engine-unowned were dropped before selection.

A/B against ecd2a1a56 (arm A), frozen held-out set, measured on this merged tree

Live arm, 10 briefs × 2 runs per arm (claude -p --model sonnet --strict-mcp-config, the arm's rule as the prompt prefix), three runs because the base arm varies with how many details the model opens:

The split is recorded in the PRD's Decisions: the row change is the smaller half (details no longer opened ≈ 1.65 KB per search, five complete rows ≈ 4.5 KB, because a row is ~900 B at p50, not the 416 B the PRD assumed), and compact serialization adds 11.8% on every response including the reference stubs. Both figures print on every harness run.

Review

Two independent opus reviews of this branch; every finding fixed.

• Surfaces the first review caught that the change had left behind: the recorded engine-mcp-tools.json description, the shared threenative-capabilities skill, the tracked packages/core/mcp/engine-server.mjs bundle, and the sixteen scaffold trees (re-measured on the merged tree).
• The name channel first matched a token subset (physics answered afterPhysics); the next shape was too strict (whole-query equality missed a node named in a sentence, and a rarity floor hid use rapier). The final rule has no rarity constant: spelling plus a share-scaled lead plus a specificity tie-break, all 20 gold exact-symbol rows and both reviewers' probe sets green.
• The harness gates live bytes on the PRD's metric, prints the stricter payload-only figure beside it, and fails closed on a live run that did not complete.
• CI then found two consequences the reviews could not: the kit router text pushed starter two words over its 1,200-word instruction budget (the line is now rows answer; engine_capability_detail only for omitted symbols, zero delta, full detail in the threenative-capabilities skill), and seven Unreal-vocabulary aliases are now recalled with the aliases stripped because their capabilities' summaries name the same words — flagged baselineAlreadyRecalled with a comment rather than deleted.

Gates

• pnpm tsx scripts/capability-search-ab.ts --base ecd2a1a56 --live --runs 2 — exit 0, every gate passes; artifact artifacts/capability-search-ab.json (local, gitignored).
• pnpm exec vitest run packages/engine-mcp — 153 passed, 1 skipped: the gold spec (20/20 names at rank 1, locked held-out floor 0.60 / 0.76), the 86 search cases, and both reviewers' probes.
• pnpm exec vitest run scripts/__tests__/kit-conventions.spec.ts scripts/__tests__/mcp-tool-schemas.spec.ts scripts/__tests__/verify-registry-install.spec.ts packages/core/__tests__/mcp-install.spec.ts packages/create-threenative/__tests__/scaffold-mcp.spec.ts scripts/__tests__/sync-agent-docs.spec.ts — 166 passed; scaffold.spec.ts green with the merged-tree hashes.
• pnpm caps:recall — 0.938053, unchanged (an earlier shape of this change cost snow.refill).
• pnpm typecheck, pnpm lint (0 errors), pnpm check:docs, pnpm sync:agents --check, pnpm quality: green.
• Pre-push ci:fast: lint and drift pass.
• pnpm build on this worktree fails only in examples/spell-lab: TN_WASM_ENGINE_MISSING (a fresh worktree has no Wasm build; packages all build).